remark-frontmatter

What is remark-frontmatter?

The remark-frontmatter package is a plugin for the remark processor that allows you to parse and manipulate frontmatter in Markdown files. Frontmatter is typically used to include metadata at the beginning of a Markdown document, often in YAML or TOML format.

What are remark-frontmatter's main functionalities?

Parsing YAML frontmatter

This feature allows you to parse YAML frontmatter in a Markdown file. The code sample demonstrates how to use the remark-frontmatter plugin to parse YAML frontmatter and process the Markdown content.

const remark = require('remark');
const frontmatter = require('remark-frontmatter');

const markdown = `---
title: Example Title
date: 2023-10-01
---

# Hello World
`;

remark()
  .use(frontmatter, ['yaml'])
  .process(markdown, function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Parsing TOML frontmatter

This feature allows you to parse TOML frontmatter in a Markdown file. The code sample demonstrates how to use the remark-frontmatter plugin to parse TOML frontmatter and process the Markdown content.

const remark = require('remark');
const frontmatter = require('remark-frontmatter');

const markdown = `+++
title = "Example Title"
date = "2023-10-01"
+++

# Hello World
`;

remark()
  .use(frontmatter, ['toml'])
  .process(markdown, function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Parsing multiple types of frontmatter

This feature allows you to parse multiple types of frontmatter (e.g., YAML and TOML) in a Markdown file. The code sample demonstrates how to use the remark-frontmatter plugin to parse both YAML and TOML frontmatter and process the Markdown content.

const remark = require('remark');
const frontmatter = require('remark-frontmatter');

const markdown = `---
title: Example Title
date: 2023-10-01
---

# Hello World
`;

remark()
  .use(frontmatter, ['yaml', 'toml'])
  .process(markdown, function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Other packages similar to remark-frontmatter

gray-matter

gray-matter is a popular package for parsing frontmatter from strings or files. It supports YAML, TOML, and JSON frontmatter. Compared to remark-frontmatter, gray-matter is more versatile as it can be used outside of the remark ecosystem and provides more features for handling frontmatter data.

front-matter

front-matter is a simple package for parsing YAML frontmatter from strings. It is lightweight and easy to use but does not support TOML or JSON frontmatter. Compared to remark-frontmatter, it is more limited in scope but can be a good choice for projects that only need to handle YAML frontmatter.

markdown-it-front-matter

markdown-it-front-matter is a plugin for the markdown-it parser that allows you to extract frontmatter from Markdown files. It supports YAML frontmatter and integrates well with the markdown-it ecosystem. Compared to remark-frontmatter, it is designed specifically for use with markdown-it rather than remark.

README

remark-frontmatter

remark plugin to support frontmatter (YAML, TOML, and more).

Install

npm:

npm install remark-frontmatter

Use

Say we have the following file, example.md:

+++
title = "New Website"
+++

# Other markdown

And our script, example.js, looks as follows:

var vfile = require('to-vfile')
var report = require('vfile-reporter')
var unified = require('unified')
var parse = require('remark-parse')
var stringify = require('remark-stringify')
var frontmatter = require('remark-frontmatter')

unified()
  .use(parse)
  .use(stringify)
  .use(frontmatter, ['yaml', 'toml'])
  .use(logger)
  .process(vfile.readSync('example.md'), function(err, file) {
    console.log(String(file))
    console.error(report(err || file))
  })

function logger() {
  return console.dir
}

Now, running node example yields:

{ type: 'root',
  children:
   [ { type: 'toml',
       value: 'title = "New Website"',
       position: [Object] },
     { type: 'heading',
       depth: 1,
       children: [Array],
       position: [Object] } ],
  position: [Object] }

example.md: no issues found
+++
title = "New Website"
+++

# Other markdown

API

remark().use(frontmatter[, options])

Support frontmatter (YAML, TOML, and more). Adds tokenizers if the processor is configured with remark-parse, and visitors if configured with remark-stringify.

If you are parsing from a different syntax, or compiling to a different syntax (such as, remark-man) your custom nodes may not be supported.

options

One preset or Matter, or an array of them, defining all the supported frontmatters (default: 'yaml').

preset

Either 'yaml' or 'toml':

• 'yaml' — matter defined as {type: 'yaml', marker: '-'}
• 'toml' — matter defined as {type: 'toml', marker: '+'}

Matter

An object with a type and either a marker or a fence:

• type (string) — Node type to parse to in mdast and compile from
• marker (string or {open: string, close: string}) — Character used to construct fences. By providing an object with open and close. different characters can be used for opening and closing fences. For example the character '-' will result in '---' being used as the fence
• fence (string or {open: string, close: string}) — String used as the complete fence. By providing an object with open and close different values can be used for opening and closing fences. This can be used too if fences contain different characters or lengths other than 3
• anywhere (boolean, default: false) – if true, matter can be found anywhere in the document. If false (default), only matter at the start of the document is recognized

Example

For {type: 'yaml', marker: '-'}:

---
key: value
---

Yields:

{
  "type": "yaml",
  "value": "key: value"
}

For {type: 'custom', marker: {open: '<', close: '>'}}:

<<<
data
>>>

Yields:

{
  "type": "custom",
  "value": "data"
}

For {type: 'custom', fence: '+=+=+=+'}:

+=+=+=+
data
+=+=+=+

Yields:

{
  "type": "custom",
  "value": "data"
}

For {type: 'json', fence: {open: '{', close: '}'}}:

{
  "key": "value"
}

Yields:

{
  "type": "json",
  "value": "\"key\": \"value\""
}

Security

Use of remark-frontmatter does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS) attacks.

Related

• remark-github — Auto-link references like in GitHub issues, PRs, and comments
• remark-math — Math support
• remark-yaml-config — Configure remark from YAML configuration

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer